---
id: Banking - PaymentLink-spec
title: "Ficha técnica"
handle: Link de pagamento
description: ""
custom_edit_url: null
---
## Escopos necessários

O token para consumir a API de Pagamentos deve ser gerado usando o [Authorization Code](https://developers.empresas.btgpactual.com/docs/authorization-code).

O escopo `openid` é obrigatório. Ele permite consultar o perfil do usuário BTG com acesso à conta.

É necessário escolher um dos seguintes escopos:

| Escopo                                   | Descrição                                                                        |
| :--------------------------------------- | :------------------------------------------------------------------------------- |
| `brn:btg:empresas:payment-link`          | Permite a criação e o manejo de links de pagamentos e o recebimento de webhooks. |
| `brn:btg:empresas:payment-link.readonly` | Permite a consulta de links de pagamentos e o recebimento de webhooks.           |

## Eventos de webhook

Os payloads disponíveis abaixo representam o conteúdo do campo `data`, seguindo o formato do envio descrito em [Eventos](https://developers.empresas.btgpactual.com/v1.5/docs/utilize-webhooks-para-receber-atualiza%C3%A7%C3%B5es-sobre-produtos-conectados#/eventos).

Por segurança, o `taxId` do pagador (`payer.taxId`) é enviado mascarado nos payloads de webhook.

| Evento                   | Descrição                                    |
| :----------------------- | :------------------------------------------- |
| `payment-link.created`   | Link de pagamento criado.                    |
| `payment-link.activated` | Link de pagamento ativado.                   |
| `payment-link.paid`      | Link de pagamento pago.                      |
| `payment-link.updated`   | Link de pagamento atualizado.                |
| `payment-link.expired`   | Link de pagamento expirado.                  |
| `payment-link.cancelled` | Link de pagamento cancelado.                 |
| `payment-link.failed`    | Falha no processamento do link de pagamento. |

### payment-link.created

```json
{
  "id": "8d241f83-6d04-457b-9cd4-eebc253a34fd",
  "name": "Link de pagamento teste",
  "payee": {
    "name": "COMDATA TELECOM LTDA",
    "personType": "J",
    "taxId": "50523744000169",
    "accountNumber": "008656317"
  },
  "payer": {
    "name": "JUAREZ BASTOS CUNHA",
    "personType": "F",
    "taxId": "***414325**"
  },
  "amount": 149,
  "paymentMethods": ["BANKSLIP"],
  "schedule": {
    "startAt": "2025-07-30T11:26:55.772Z",
    "endAt": "2025-08-15T11:26:55.772Z"
  },
  "createdAt": "2025-07-30",
  "updatedAt": "2025-07-30",
  "origin": "DEVELOPERS",
  "deliveryMediums": [],
  "linkUrl": "https://link.btgpactual.com/8d241f83",
  "type": "SINGLE"
}
```

### payment-link.activated

```json
{
  "id": "8d241f83-6d04-457b-9cd4-eebc253a34fd",
  "name": "Link de pagamento teste",
  "payee": {
    "name": "COMDATA TELECOM LTDA",
    "personType": "J",
    "taxId": "50523744000169",
    "accountNumber": "008656317"
  },
  "payer": {
    "name": "JUAREZ BASTOS CUNHA",
    "personType": "F",
    "taxId": "***414325**"
  },
  "amount": 149,
  "paymentMethods": ["BANKSLIP"],
  "schedule": {
    "startAt": "2025-07-30T11:26:55.772Z",
    "endAt": "2025-08-15T11:26:55.772Z"
  },
  "createdAt": "2025-07-30",
  "updatedAt": "2025-07-30",
  "origin": "DEVELOPERS",
  "deliveryMediums": [],
  "linkUrl": "https://link.btgpactual.com/8d241f83",
  "type": "SINGLE"
}
```

### payment-link.paid

```json
{
  "id": "8d241f83-6d04-457b-9cd4-eebc253a34fd",
  "name": "Link de pagamento teste",
  "payee": {
    "name": "COMDATA TELECOM LTDA",
    "personType": "J",
    "taxId": "50523744000169",
    "accountNumber": "008656317"
  },
  "payer": {
    "name": "JUAREZ BASTOS CUNHA",
    "personType": "F",
    "taxId": "***414325**"
  },
  "amount": 149,
  "paymentMethods": ["BANKSLIP"],
  "schedule": {
    "startAt": "2025-07-30T11:26:55.772Z",
    "endAt": "2025-08-15T11:26:55.772Z"
  },
  "createdAt": "2025-07-30",
  "updatedAt": "2025-08-11",
  "origin": "DEVELOPERS",
  "deliveryMediums": [],
  "linkUrl": "https://link.btgpactual.com/8d241f83",
  "type": "SINGLE"
}
```

### payment-link.updated

```json
{
  "id": "8d241f83-6d04-457b-9cd4-eebc253a34fd",
  "name": "Link de pagamento teste",
  "payee": {
    "name": "COMDATA TELECOM LTDA",
    "personType": "J",
    "taxId": "50523744000169",
    "accountNumber": "008656317"
  },
  "payer": {
    "name": "JUAREZ BASTOS CUNHA",
    "personType": "F",
    "taxId": "***414325**"
  },
  "amount": 149,
  "paymentMethods": ["BANKSLIP"],
  "schedule": {
    "startAt": "2025-07-30T11:26:55.772Z",
    "endAt": "2025-08-15T11:26:55.772Z"
  },
  "createdAt": "2025-07-30",
  "updatedAt": "2025-08-11",
  "origin": "DEVELOPERS",
  "deliveryMediums": [],
  "linkUrl": "https://link.btgpactual.com/8d241f83",
  "type": "SINGLE"
}
```

### payment-link.expired

```json
{
  "id": "8d241f83-6d04-457b-9cd4-eebc253a34fd",
  "name": "Link de pagamento teste",
  "payee": {
    "name": "COMDATA TELECOM LTDA",
    "personType": "J",
    "taxId": "50523744000169",
    "accountNumber": "008656317"
  },
  "payer": {
    "name": "JUAREZ BASTOS CUNHA",
    "personType": "F",
    "taxId": "***414325**"
  },
  "amount": 149,
  "paymentMethods": ["BANKSLIP"],
  "schedule": {
    "startAt": "2025-07-30T11:26:55.772Z",
    "endAt": "2025-08-15T11:26:55.772Z"
  },
  "createdAt": "2025-07-30",
  "updatedAt": "2025-08-15",
  "origin": "DEVELOPERS",
  "deliveryMediums": [],
  "linkUrl": "https://link.btgpactual.com/8d241f83",
  "type": "SINGLE"
}
```

### payment-link.cancelled

```json
{
  "id": "8d241f83-6d04-457b-9cd4-eebc253a34fd",
  "name": "Link de pagamento teste",
  "payee": {
    "name": "COMDATA TELECOM LTDA",
    "personType": "J",
    "taxId": "50523744000169",
    "accountNumber": "008656317"
  },
  "payer": {
    "name": "JUAREZ BASTOS CUNHA",
    "personType": "F",
    "taxId": "***414325**"
  },
  "amount": 149,
  "paymentMethods": ["BANKSLIP"],
  "schedule": {
    "startAt": "2025-07-30T11:26:55.772Z",
    "endAt": "2025-08-15T11:26:55.772Z"
  },
  "createdAt": "2025-07-30",
  "updatedAt": "2025-08-11",
  "origin": "DEVELOPERS",
  "deliveryMediums": [],
  "linkUrl": "https://link.btgpactual.com/8d241f83",
  "type": "SINGLE"
}
```

### payment-link.failed

```json
{
  "id": "8d241f83-6d04-457b-9cd4-eebc253a34fd",
  "name": "Link de pagamento teste",
  "payee": {
    "name": "COMDATA TELECOM LTDA",
    "personType": "J",
    "taxId": "50523744000169",
    "accountNumber": "008656317"
  },
  "payer": {
    "name": "JUAREZ BASTOS CUNHA",
    "personType": "F",
    "taxId": "***414325**"
  },
  "amount": 149,
  "paymentMethods": ["BANKSLIP"],
  "schedule": {
    "startAt": "2025-07-30T11:26:55.772Z",
    "endAt": "2025-08-15T11:26:55.772Z"
  },
  "createdAt": "2025-07-30",
  "updatedAt": "2025-08-11",
  "origin": "DEVELOPERS",
  "deliveryMediums": [],
  "linkUrl": "https://link.btgpactual.com/8d241f83",
  "type": "SINGLE"
}
```